superagent

What is superagent?

The superagent npm package is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. It is designed to make HTTP requests from both Node.js and browsers.

What are superagent's main functionalities?

GET requests

This feature allows you to make GET requests to retrieve data from a server. You can include query parameters and handle the response asynchronously.

superagent.get('/search').query({ query: 'Manny' }).end(function(err, res){ /* handling response */ });

POST requests

This feature is used to send POST requests to a server. You can send data as part of the request body and set custom headers.

superagent.post('/api/pets').send({ name: 'Manny', species: 'cat' }).set('X-API-Key', 'foobar').end(function(err, res){ /* handling response */ });

Handling responses

This feature allows you to handle responses from the server, checking if the request was successful and then acting on the data received.

superagent.get('/some-url').end(function(err, res){ if (res.ok) { console.log('yay got ' + JSON.stringify(res.body)); } else { console.log('Oh no! error ' + res.text); } });

Promises and async/await

Superagent can be used with promises and async/await syntax for better asynchronous control flow.

async function getData() { try { const res = await superagent.get('/some-url'); console.log(res.body); } catch (err) { console.error(err); } }

Pipelining requests

This feature allows you to pipe the response stream directly to a file or another writable stream.

superagent.get('/some-url').pipe(fs.createWriteStream('result.txt'))

Other packages similar to superagent

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a simple API and handles requests and responses in JSON format. Compared to superagent, it has built-in CSRF protection and supports interceptors for request and response transformation.

fetch

The Fetch API provides a more modern alternative to XMLHttpRequest for making HTTP requests in the browser. It is not an npm package but a built-in browser API. It returns promises and works with async/await. Unlike superagent, it is not Node.js compatible without polyfills.

got

Got is a Node.js HTTP request library that is designed to be a simpler and more user-friendly alternative to Node's native 'http' module. It supports promises and async/await, streams, and advanced features like retries and timeouts. It is often compared to superagent for its simplicity and feature set.

node-fetch

node-fetch is a light-weight module that brings the browser Fetch API to Node.js. It is similar to superagent but is designed to mimic the Fetch API as closely as possible. It is promise-based and supports stream consumption.

request

Request is a simplified HTTP request client for Node.js, but it has been deprecated. It was known for its simplicity and wide adoption. Superagent offers a similar feature set but continues to be maintained and updated.

README

superagent

Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features

Table of Contents

• Install
• Usage
  • Node
  • Browser
• Supported Platforms
  • Required Browser Features
• Plugins
• Upgrading from previous versions
• Contributors
• License

Install

npm:

npm install superagent

yarn:

yarn add superagent

Usage

Node

const superagent = require('superagent');

// callback
superagent
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
  .set('X-API-Key', 'foobar')
  .set('accept', 'json')
  .end((err, res) => {
    // Calling the end function will send the request
  });

// promise with then/catch
superagent.post('/api/pet').then(console.log).catch(console.error);

// promise with async/await
(async () => {
  try {
    const res = await superagent.post('/api/pet');
    console.log(res);
  } catch (err) {
    console.error(err);
  }
})();

Browser

The browser-ready, minified version of superagent is only 6 KB (minified and gzipped)!

Browser-ready versions of this module are available via jsdelivr, unpkg, and also in the node_modules/superagent/dist folder in downloads of the superagent package.

Note that we also provide unminified versions with .js instead of .min.js file extensions.

VanillaJS

This is the solution for you if you're just using <script> tags everywhere!

<script src="https://polyfill.io/v3/polyfill.min.js?features=Array.from,Promise,Symbol,Object.setPrototypeOf,Object.getOwnPropertySymbols,Set,Math.trunc,BigInt,Map,Reflect,WeakMap,WeakRef,WeakSet,BigInt,Map,Reflect,WeakMap,WeakRef,WeakSet"></script>
<script src="https://cdn.jsdelivr.net/npm/superagent"></script>
<!-- if you wish to use unpkg.com instead: -->
<!-- <script src="https://unpkg.com/superagent"></script> -->
<script type="text/javascript">
  (function() {
    // superagent is exposed as `window.superagent`
    // if you wish to use "request" instead please
    // uncomment the following line of code:
    // `window.request = superagent;`
    superagent
      .post('/api/pet')
      .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
      .set('X-API-Key', 'foobar')
      .set('accept', 'json')
      .end(function (err, res) {
        // Calling the end function will send the request
      });
  })();
</script>

Bundler

If you are using browserify, webpack, rollup, or another bundler, then you can follow the same usage as Node above.

Supported Platforms

• Node: v6.x+

• Browsers (see .browserslistrc):

  npx browserslist
  

  and_chr 71
  and_ff 64
  and_qq 1.2
  and_uc 11.8
  android 67
  android 4.4.3-4.4.4
  baidu 7.12
  bb 10
  bb 7
  chrome 73
  chrome 72
  chrome 71
  edge 18
  edge 17
  firefox 66
  firefox 65
  ie 11
  ie 10
  ie 9
  ie_mob 11
  ie_mob 10
  ios_saf 12.0-12.1
  ios_saf 11.3-11.4
  op_mini all
  op_mob 46
  op_mob 12.1
  opera 58
  opera 57
  safari 12
  safari 11.1
  samsung 8.2
  samsung 7.2-7.4
  

Required Browser Features

We recommend using https://polyfill.io (specifically with the bundle mentioned in VanillaJS above):

<script src="https://polyfill.io/v3/polyfill.min.js?features=Array.from,Promise,Symbol,Object.setPrototypeOf,Object.getOwnPropertySymbols,Set,Math.trunc,BigInt,Map,Reflect,WeakMap,WeakRef,WeakSet"></script>

• IE 9-10 requires a polyfill for Promise, Array.from, Symbol, Object.getOwnPropertySymbols, and Object.setPrototypeOf
• IE 9 requires a polyfill for window.FormData (we recommend formdata-polyfill), Set, Math.trunc, BigInt, Map, Reflect, WeakMap, WeakRef, and WeakSet

Plugins

SuperAgent is easily extended via plugins.

const nocache = require('superagent-no-cache');
const superagent = require('superagent');
const prefix = require('superagent-prefix')('/static');

superagent
  .get('/some-url')
  .query({ action: 'edit', city: 'London' }) // query string
  .use(prefix) // Prefixes *only* this request
  .use(nocache) // Prevents caching of *only* this request
  .end((err, res) => {
    // Do something
  });

Existing plugins:

• superagent-no-cache - prevents caching by including Cache-Control header
• superagent-prefix - prefixes absolute URLs (useful in test environment)
• superagent-suffix - suffix URLs with a given path
• superagent-mock - simulate HTTP calls by returning data fixtures based on the requested URL
• superagent-mocker — simulate REST API
• superagent-cache - A global SuperAgent patch with built-in, flexible caching
• superagent-cache-plugin - A SuperAgent plugin with built-in, flexible caching
• superagent-jsonapify - A lightweight json-api client addon for superagent
• superagent-serializer - Converts server payload into different cases
• superagent-httpbackend - stub out requests using AngularJS' $httpBackend syntax
• superagent-throttle - queues and intelligently throttles requests
• superagent-charset - add charset support for node's SuperAgent
• superagent-verbose-errors - include response body in error messages for failed requests
• superagent-declare - A simple declarative API for SuperAgent
• superagent-node-http-timings - measure http timings in node.js

Please prefix your plugin with superagent-* so that it can easily be found by others.

For SuperAgent extensions such as couchdb and oauth visit the wiki.

Upgrading from previous versions

Please see GitHub releases page for the current changelog.

Our breaking changes are mostly in rarely used functionality and from stricter error handling.

• 6.0 to 6.1
  • Browser behaviour changed to match Node when serializing application/x-www-form-urlencoded, using arrayFormat: 'indices' semantics of qs library. (See: https://www.npmjs.com/package/qs#stringifying)
• 5.x to 6.x:
  • Retry behavior is still opt-in, however we now have a more fine-grained list of status codes and error codes that we retry against (see updated docs)
  • A specific issue with Content-Type matching not being case-insensitive is fixed
  • Set is now required for IE 9, see Required Browser Features for more insight
• 4.x to 5.x:
  • We've implemented the build setup of Lass to simplify our stack and linting
  • Unminified browserified build size has been reduced from 48KB to 20KB (via tinyify and the latest version of Babel using @babel/preset-env and .browserslistrc)
  • Linting support has been added using caniuse-lite and eslint-plugin-compat
  • We can now target what versions of Node we wish to support more easily using .babelrc
• 3.x to 4.x:
  • Ensure you're running Node 6 or later. We've dropped support for Node 4.
  • We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
  • We suggest migrating from .end() callbacks to .then() or await.
• 2.x to 3.x:
  • Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
  • Test code that calls .send() multiple times. Invalid calls to .send() will now throw instead of sending garbage.
• 1.x to 2.x:
  • If you use .parse() in the browser version, rename it to .serialize().
  • If you rely on undefined in query-string values being sent literally as the text "undefined", switch to checking for missing value instead. ?key=undefined is now ?key (without a value).
  • If you use .then() in Internet Explorer, ensure that you have a polyfill that adds a global Promise object.
• 0.x to 1.x:
  • Instead of 1-argument callback .end(function(res){}) use .then(res => {}).

Contributors

Name
Kornel Lesiński
Peter Lyons
Hunter Loftis
Nick Baugh

License

MIT © TJ Holowaychuk